home *** CD-ROM | disk | FTP | other *** search
/ Mac Magazin/MacEasy 43 / Mac Magazin and MacEasy Magazine CD - Issue 43.iso / Software / Mobiles Büro / Newton / Newton Entwickler / DIL 2.0 Mac OS ƒ / Headers / FDIL.h < prev    next >
Text File  |  1997-09-19  |  14KB  |  493 lines
  1. /*
  2.     File:        FDIL.h, v2.0a2
  3.  
  4.     Contains:    Public interface to the Desktop Integration Library
  5.  
  6.     Copyright:    Apple Computer, Inc. 1997, all rights reserved.
  7. */
  8.  
  9. #ifndef __FDIL_H
  10. #define __FDIL_H
  11.  
  12. #include "DIL.h"
  13.  
  14. #ifdef __cplusplus
  15. extern "C" {
  16. #endif
  17.  
  18. #ifdef DIL_ForDebug
  19.     #define FD_TrackMemory        1
  20. #else
  21.     #define FD_HandleIsOpaque    1
  22. #endif
  23.  
  24. /* --- FDIL error numbers --- */
  25.  
  26.     /* Hard errors -- you should always be looking for these. */
  27.  
  28. #define kFD_UnknownStreamVersion        (kFD_ErrorBase - 1)
  29. #define kFD_StreamCorrupted                (kFD_ErrorBase - 2)
  30. #define kFD_UnsupportedCompression        (kFD_ErrorBase - 3)
  31. #define kFD_CouldNotCompressData        (kFD_ErrorBase - 4)
  32. #define kFD_CouldNotDecompressData        (kFD_ErrorBase - 5)
  33. #define kFD_UnsupportedStoreVersion        (kFD_ErrorBase - 6)
  34. #define kFD_ErrorCreatingStore            (kFD_ErrorBase - 7)
  35. #define kFD_ErrorWritingToStore            (kFD_ErrorBase - 8)
  36. #define kFD_ErrorReadingFromStore        (kFD_ErrorBase - 9)
  37.  
  38.     /* Soft errors -- you get these only if you feed in bad data. */
  39.  
  40. #define kFD_FDILNotInitialized            (kFD_ErrorBase - 19)
  41.  
  42. #define kFD_ExpectedInteger                (kFD_ErrorBase - 20)
  43. #define kFD_ExpectedPointerObject        (kFD_ErrorBase - 21)
  44. #define kFD_ExpectedImmediate            (kFD_ErrorBase - 22)
  45. #define kFD_ExpectedMagicPointer        (kFD_ErrorBase - 23)
  46.  
  47. #define kFD_ExpectedArray                (kFD_ErrorBase - 24)
  48. #define kFD_ExpectedFrame                (kFD_ErrorBase - 25)
  49. #define kFD_ExpectedBinary                (kFD_ErrorBase - 26)
  50. #define kFD_ExpectedLargeBinary            (kFD_ErrorBase - 27)
  51.  
  52. #define kFD_ExpectedReal                (kFD_ErrorBase - 28)
  53. #define kFD_ExpectedString                (kFD_ErrorBase - 29)
  54. #define kFD_ExpectedSymbol                (kFD_ErrorBase - 30)
  55. #define kFD_ExpectedChar                (kFD_ErrorBase - 31)
  56.  
  57. #define kFD_NULLPointer                    (kFD_ErrorBase - 40)
  58. #define kFD_ExpectedPositiveValue        (kFD_ErrorBase - 41)
  59. #define kFD_ExpectedNonNegativeValue    (kFD_ErrorBase - 42)
  60. #define kFD_ValueOutOfRange                (kFD_ErrorBase - 43)
  61. #define kFD_SymbolTooLong                (kFD_ErrorBase - 44)
  62. #define kFD_IllegalCharInSymbol            (kFD_ErrorBase - 45)
  63. #define kFD_InvalidClass                (kFD_ErrorBase - 46)
  64. #define kFD_PointerObjectIsFree            (kFD_ErrorBase - 47)
  65.  
  66.     /* Internal errors -- you should never see these. */
  67.  
  68. #define kFD_LBReadingFromUnwrittenPage    (kFD_ErrorBase - 50)
  69.  
  70.  
  71. /*
  72. **    The FD_Handle type
  73. */
  74.  
  75. #ifdef FD_HandleIsOpaque
  76.     typedef long        FD_Handle;
  77. #else
  78.     struct FD_ObjectHeader;
  79.     typedef struct FD_Handle
  80.     {
  81.         long    ref;
  82.         struct FD_ObjectHeader**    entry;
  83.     } FD_Handle;
  84. #endif
  85.  
  86.  
  87. /*
  88. **    Handy common values. Use them as values passed in to
  89. **    functions. Never compare (using FD_Equal) an object to
  90. **    them to see if it's NIL or not. Instead, use FD_IsNIL
  91. **    and FD_NotNIL.
  92. */
  93.  
  94. DILAPI extern FD_Handle    kFD_NIL;
  95. DILAPI extern FD_Handle    kFD_True;
  96.  
  97.  
  98. /*
  99. **    Values returned by FD_GetClass (in addition to kFD_NIL
  100. **    and classes you define).
  101. */
  102.  
  103. DILAPI extern FD_Handle    kFD_SymArray;
  104. DILAPI extern FD_Handle    kFD_SymBoolean;
  105. DILAPI extern FD_Handle    kFD_SymChar;
  106. DILAPI extern FD_Handle    kFD_SymInteger;
  107. DILAPI extern FD_Handle    kFD_SymFrame;
  108. DILAPI extern FD_Handle    kFD_SymMagicPointer;
  109. DILAPI extern FD_Handle    kFD_SymReal;
  110. DILAPI extern FD_Handle    kFD_SymString;
  111. DILAPI extern FD_Handle    kFD_SymSymbol;
  112. DILAPI extern FD_Handle    kFD_SymWeird_Immediate;
  113.  
  114.  
  115. /*
  116. **    Values that can be specified for the second
  117. **    parameter of FD_MakeImmediate.
  118. */
  119.  
  120. typedef enum FD_ImmediateType
  121. {
  122.     kFD_ImmedSpecial = 0,
  123.     kFD_ImmedChar,
  124.     kFD_ImmedBoolean,
  125.     kFD_ImmedReserved
  126. } FD_ImmediateType;
  127.  
  128.  
  129. /*
  130. **    Compression types for FD_MakeLargeBinary.
  131. */
  132.  
  133. typedef enum FD_CompressionType
  134. {
  135.     kFD_NoCompression,
  136.     kFD_LZCompression,
  137.     kFD_ZippyCompression
  138. } FD_CompressionType;
  139.  
  140.  
  141. /*
  142. ** Forward declarations of Large Binary structures.
  143. */
  144.  
  145. struct FD_LargeBinaryProcs;
  146. typedef struct FD_LargeBinaryProcs FD_LargeBinaryProcs;
  147.  
  148.  
  149. /*
  150. **    Startup/Shutdown
  151. */
  152.  
  153. DILAPI DIL_Error    FD_Startup                (void);
  154. DILAPI DIL_Error    FD_Shutdown                (void);
  155.  
  156.  
  157. /*
  158. **    Error handling
  159. */
  160.  
  161. DILAPI DIL_Error    FD_GetError                (void);
  162.  
  163.  
  164. /*
  165. **    Create objects
  166. */
  167.  
  168. DILAPI FD_Handle    FD_MakeInt                (long);
  169.  
  170. DILAPI FD_Handle    FD_MakeReal                (double);
  171. DILAPI FD_Handle    FD_MakeString            (const char*);
  172. DILAPI FD_Handle    FD_MakeWideString        (const DIL_WideChar*);
  173. DILAPI FD_Handle    FD_MakeSymbol            (const char*);
  174. DILAPI FD_Handle    FD_MakeArray            (long size, const char* objClass);
  175. DILAPI FD_Handle    FD_MakeFrame            (void);
  176. DILAPI FD_Handle    FD_MakeBinary            (long size, const char* objClass);
  177.  
  178. DILAPI FD_Handle    FD_MakeChar                (char);
  179. DILAPI FD_Handle    FD_MakeWideChar            (DIL_WideChar);
  180.  
  181. DILAPI FD_Handle    FD_MakeImmediate        (long type, long value);
  182. DILAPI FD_Handle    FD_MakeMagicPointer        (long value);
  183. DILAPI FD_Handle    FD_MakeLargeBinary        (long size,
  184.                                                 const char* objClass,
  185.                                                 long compressionType);
  186.  
  187.  
  188. /*
  189. **    Delete objects
  190. */
  191.  
  192. DILAPI DIL_Error    FD_Dispose                (FD_Handle);
  193. DILAPI DIL_Error    FD_DeepDispose            (FD_Handle);
  194.  
  195. DILAPI long        FD_AllocatedMemory        (void);
  196.  
  197.  
  198. /*
  199. **    Object predicates
  200. */
  201.  
  202. DILAPI int            FD_IsInt                (FD_Handle);
  203. DILAPI int            FD_IsPointerObject        (FD_Handle);
  204.  
  205. DILAPI int            FD_IsReal                (FD_Handle);
  206. DILAPI int            FD_IsString                (FD_Handle);
  207. DILAPI int            FD_IsRichString            (FD_Handle);
  208. DILAPI int            FD_IsSymbol                (FD_Handle);
  209. DILAPI int            FD_IsArray                (FD_Handle);
  210. DILAPI int            FD_IsFrame                (FD_Handle);
  211. DILAPI int            FD_IsBinary                (FD_Handle);
  212.  
  213. DILAPI int            FD_IsChar                (FD_Handle);
  214.  
  215. DILAPI int            FD_IsFree                (FD_Handle);
  216.  
  217. DILAPI int            FD_IsImmediate            (FD_Handle);
  218. DILAPI int            FD_IsMagicPointer        (FD_Handle);
  219. DILAPI int            FD_IsBoolean            (FD_Handle);
  220. DILAPI int            FD_IsLargeBinary        (FD_Handle);
  221.  
  222. DILAPI int            FD_IsSubClass            (FD_Handle, const char*);
  223.  
  224.  
  225. /*
  226. **    Data accessors.
  227. **
  228. **    FD_GetString and FD_GetWideString work like strncpy: bufLen characters
  229. **    will be copied. If there's enough room, a terminating NULL will be added.
  230. **    They differ from strncpy in that they will not necessarily pad out the
  231. **    rest of the buffer with NULLs.
  232. */
  233.  
  234. DILAPI long        FD_GetInt                (FD_Handle);
  235.  
  236. DILAPI double        FD_GetReal                (FD_Handle);
  237. DILAPI DIL_Error    FD_GetString            (FD_Handle, char*, long bufLen);
  238. DILAPI DIL_Error    FD_GetWideString        (FD_Handle, DIL_WideChar*, long bufLen);
  239. DILAPI const char*    FD_GetSymbol            (FD_Handle);
  240. DILAPI void*        FD_GetBinaryData        (FD_Handle);
  241.  
  242. DILAPI char        FD_GetChar                (FD_Handle);
  243. DILAPI DIL_WideChar FD_GetWideChar            (FD_Handle);
  244.  
  245. DILAPI int            FD_IsNIL                (FD_Handle);
  246. DILAPI int            FD_NotNIL                (FD_Handle);
  247.  
  248. DILAPI FD_Handle    FD_ASCIIString            (FD_Handle);
  249.  
  250. DILAPI DIL_Error    FD_GetImmediate            (FD_Handle, long* type, long* value);
  251. DILAPI long        FD_GetMagicPointer        (FD_Handle);
  252. DILAPI DIL_Error    FD_ReadFromLargeBinary    (FD_Handle, long offset, void*, long count);
  253. DILAPI DIL_Error    FD_WriteToLargeBinary    (FD_Handle, long offset, const void*, long count);
  254.  
  255. DILAPI DIL_Error    FD_SetLargeBinaryProcs    (const FD_LargeBinaryProcs*);
  256.  
  257.  
  258. /*
  259. **    Array manipulation
  260. */
  261.  
  262. DILAPI DIL_Error    FD_InsertArraySlot        (FD_Handle array, long pos, FD_Handle item);
  263. DILAPI DIL_Error    FD_AppendArraySlot        (FD_Handle array, FD_Handle item);
  264. DILAPI FD_Handle    FD_RemoveArraySlot        (FD_Handle array, long pos);
  265. DILAPI DIL_Error    FD_RemoveArraySlotCount    (FD_Handle array, long pos, long count);
  266. DILAPI FD_Handle    FD_SetArraySlot            (FD_Handle array, long pos, FD_Handle item);
  267. DILAPI FD_Handle    FD_GetArraySlot            (FD_Handle array, long pos);
  268.  
  269.  
  270. /*
  271. **    Frame manipulation
  272. */
  273.  
  274. DILAPI FD_Handle    FD_SetFrameSlot            (FD_Handle frame, const char* slotName, FD_Handle item);
  275. DILAPI FD_Handle    FD_GetFrameSlot            (FD_Handle frame, const char* slotName);
  276. DILAPI int            FD_FrameHasSlot            (FD_Handle frame, const char* slotName);
  277. DILAPI FD_Handle    FD_RemoveFrameSlot        (FD_Handle frame, const char* slotName);
  278.  
  279. DILAPI FD_Handle    FD_GetIndFrameSlot        (FD_Handle frame, long pos);
  280. DILAPI FD_Handle    FD_GetIndFrameSlotName    (FD_Handle frame, long pos);
  281.  
  282.  
  283. /*
  284. **    Heap object manipulation
  285. */
  286.  
  287. DILAPI DIL_Error    FD_SetClass                (FD_Handle, FD_Handle oClass);
  288. DILAPI long        FD_GetLength            (FD_Handle);
  289. DILAPI DIL_Error    FD_SetLength            (FD_Handle, long newSize);
  290.  
  291.  
  292. /*
  293. **    Any object manipulation
  294. */
  295.  
  296. DILAPI FD_Handle    FD_GetClass                (FD_Handle);
  297.  
  298.  
  299. /*
  300. **    Object comparison
  301. */
  302.  
  303. DILAPI int            FD_Equal                (FD_Handle, FD_Handle);
  304.  
  305.  
  306. /*
  307. **    Object duplication
  308. */
  309.  
  310. DILAPI FD_Handle    FD_Clone                (FD_Handle);
  311. DILAPI FD_Handle    FD_DeepClone            (FD_Handle);
  312.  
  313.  
  314. /*
  315. **    Object streaming
  316. */
  317.  
  318. DILAPI DIL_Error    FD_Flatten                (FD_Handle, DIL_WriteProc, void* userData);
  319. DILAPI FD_Handle    FD_Unflatten            (DIL_ReadProc, void* userData);
  320.  
  321.  
  322. /*
  323. **    FD_PrintObject converts an object into some user-readable
  324. **    text form. For instance, a frame will be turned into text
  325. **    looking something like the following:
  326. **
  327. **        {
  328. **            name:    "Fred",
  329. **            age:    15,
  330. **            phone:    [
  331. **                        {
  332. **                            'home,
  333. **                            "555-1212"
  334. **                        },
  335. **                        {
  336. **                            'work,
  337. **                            "555-2121"
  338. **                        }
  339. **                    ]
  340. **            ...
  341. **        }
  342. **
  343. **    As the text is generated, the DIL_WriteProc is called so that
  344. **    the application can deal with it as it deems fit. For instance,
  345. **    the app could buffer all the text into a Handle or CString
  346. **    object, or it could just turn around and call printf("%s", str)
  347. **    with it.
  348. */
  349.  
  350. DILAPI DIL_Error    FD_PrintObject            (FD_Handle obj,
  351.                                                 const char* EOLString,
  352.                                                 DIL_WriteProc,
  353.                                                 void* userData);
  354.  
  355.  
  356. /*
  357. **    Wide character conversion routines. These routines are written
  358. **    in such a way that you can use the same buffer as the source and
  359. **    destination. Also, since they work with NewtonScript-native
  360. **    strings, the NS_WideChars are or should be in big-endian format.
  361. */
  362.  
  363. enum {
  364.     kFD_MacEncoding,
  365.     kFD_WindowsEncoding,
  366. #ifdef macintosh
  367.     kFD_DefaultEncoding = kFD_MacEncoding
  368. #else
  369.     kFD_DefaultEncoding = kFD_WindowsEncoding
  370. #endif
  371. };
  372.  
  373. DILAPI DIL_Error    FD_ConvertFromWideChar    (char* dest,
  374.                                                 const DIL_WideChar* src,
  375.                                                 long numChars);
  376. DILAPI DIL_Error    FD_ConvertToWideChar    (DIL_WideChar* dest,
  377.                                                 const char* src,
  378.                                                 long numChars);
  379. DILAPI DIL_Error    FD_SetWideCharEncoding    (long encoding);
  380.  
  381.  
  382. /*
  383. **    Pages are passed around in FD_PageBuffs. These buffers are used to contain
  384. **    both compressed and uncompressed data. The amount of the buffer that's
  385. **    actually used in the compressed case is stored in fLength.
  386. */
  387.  
  388. #define kFD_PageChunkSize        (1024L)
  389. #define kFD_CompressionExtra    (288L)
  390.  
  391. typedef struct FD_PageBuff
  392. {
  393.     long    fLength;
  394.     char    fData[kFD_PageChunkSize + kFD_CompressionExtra];
  395.                     /* Only fLength bytes used */
  396. } FD_PageBuff;
  397.  
  398.  
  399. /*
  400. **    Functions needed to support large binary objects.
  401. **    Any of these can be NULL if desired.
  402. */
  403.  
  404. struct FD_LargeBinaryProcs
  405. {
  406.     DIL_Error    (*Create)        (void**);
  407.     DIL_Error    (*SetNumPages)    (void**, long pageCount);
  408.     DIL_Error    (*ReadPage)        (void**, long pageNum, FD_PageBuff*);
  409.     DIL_Error    (*WritePage)    (void**, long pageNum, const FD_PageBuff*);
  410.     DIL_Error    (*Destroy)        (void**);
  411. };
  412.  
  413.  
  414. /*
  415. **    Stock large binary functions you can use if you want. gNullStoreProcs
  416. **    merely read and discard the data. gMemoryStoreProcs read the data into
  417. **    memory and keep it there. gDiskStoreProcs store the data in tempory
  418. **    files on disk (which are deleted when the Destroy proc is called).
  419. */
  420.  
  421. DILAPI extern const FD_LargeBinaryProcs    kFD_NullStoreProcs;
  422. DILAPI extern const FD_LargeBinaryProcs    kFD_MemoryStoreProcs;
  423. DILAPI extern const FD_LargeBinaryProcs    kFD_DiskStoreProcs;
  424.  
  425.  
  426. /*
  427. **    Versions of the above functions that allocate memory.
  428. **    These versions record the file and line that made the allocation.
  429. **    FD_CheckForMemoryLeaks will then report that location when it
  430. **    detects memory leaks.
  431. */
  432.  
  433. #ifdef FD_TrackMemory
  434.  
  435. DILAPI FD_Handle    FDT_MakeReal        (double,                    const char*, long);
  436. DILAPI FD_Handle    FDT_MakeString        (const char*,                const char*, long);
  437. DILAPI FD_Handle    FDT_MakeWideString    (const DIL_WideChar*,        const char*, long);
  438. DILAPI FD_Handle    FDT_MakeSymbol        (const char*,                const char*, long);
  439. DILAPI FD_Handle    FDT_MakeArray        (long, const char*,            const char*, long);
  440. DILAPI FD_Handle    FDT_MakeFrame        (                            const char*, long);
  441. DILAPI FD_Handle    FDT_MakeBinary        (long, const char*,            const char*, long);
  442. DILAPI FD_Handle    FDT_MakeLargeBinary    (long, const char*, long,    const char*, long);
  443. DILAPI FD_Handle    FDT_Clone            (FD_Handle,                    const char*, long);
  444. DILAPI FD_Handle    FDT_DeepClone        (FD_Handle,                    const char*, long);
  445. DILAPI FD_Handle    FDT_Unflatten        (DIL_ReadProc, void*,        const char*, long);
  446.  
  447. #define    FD_MakeReal(v)                FDT_MakeReal        (v,            __FILE__, __LINE__)
  448. #define    FD_MakeString(v)            FDT_MakeString        (v,            __FILE__, __LINE__)
  449. #define    FD_MakeWideString(v)        FDT_MakeWideString    (v,            __FILE__, __LINE__)
  450. #define    FD_MakeSymbol(v)            FDT_MakeSymbol        (v,            __FILE__, __LINE__)
  451. #define    FD_MakeArray(v, c)            FDT_MakeArray        (v, c,        __FILE__, __LINE__)
  452. #define    FD_MakeFrame()                FDT_MakeFrame        (            __FILE__, __LINE__)
  453. #define    FD_MakeBinary(v, c)            FDT_MakeBinary        (v, c,        __FILE__, __LINE__)
  454. #define    FD_MakeLargeBinary(v, c, t)    FDT_MakeLargeBinary    (v, c, t,    __FILE__, __LINE__)
  455. #define    FD_Clone(v)                    FDT_Clone            (v,            __FILE__, __LINE__)
  456. #define    FD_DeepClone(v)                FDT_DeepClone        (v,            __FILE__, __LINE__)
  457. #define    FD_Unflatten(v, d)            FDT_Unflatten        (v, d,        __FILE__, __LINE__)
  458.  
  459. DILAPI long        FD_CheckForMemoryLeaks(const char* EOLString, DIL_WriteProc, void* userData);
  460.  
  461. #endif    /* FD_TrackMemory */
  462.  
  463.  
  464. /*
  465.     Macro magic to make sure the right library is used in conjuction with
  466.     the right preprocessor options. If you define DIL_ForDebug, then you
  467.     MUST link with the debug version of the FDIL. If you don't define
  468.     DIL_ForDebug, then you MUST link with the release version of the FDIL.
  469.     Failing to do so will cause FD_Startup() to break into the debugger
  470.     when called.
  471.  
  472.     Also, floating point values manipulated by the Newton OS and, hence,
  473.     by this library must be in standard IEEE-754 format. Passing the size
  474.     of doubles to the library helps assure that the right compiler options
  475.     are being used.
  476. */
  477.  
  478. DILAPI DIL_Error        FD_RealStartup(long DIL_ForDebug_defined, long sizeOfDouble);
  479. #ifdef DIL_ForDebug
  480.     #define FD_Startup()    FD_RealStartup(1, sizeof(double))
  481. #else
  482.     #define FD_Startup()    FD_RealStartup(0, sizeof(double))
  483. #endif
  484.  
  485.  
  486. #ifdef __cplusplus
  487. }    /* extern "C" */
  488. #endif
  489.  
  490. #endif    /* __FDIL_H */
  491.  
  492.  
  493.